/**
 * File:   dofbot.h
 * Author: AWTK Develop Team
 * Brief:  dofbot c apis
 *
 * Copyright (c) 2025 - 2025 Guangzhou ZHIYUAN Electronics Co.,Ltd.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * License file for more details.
 *
 */

/**
 * History:
 * ================================================================
 * 2025-04-05 Li XianJing <xianjimli@hotmail.com> created
 *
 */

#include "tkc.h"

#ifndef TK_DOFBOT_H
#define TK_DOFBOT_H

/**
 * @class dofbot_t
 * 通过串口访问DOFBOT机器人。
 */
struct _dofbot_t;
typedef struct _dofbot_t dofbot_t;

BEGIN_C_DECLS

/**
 * @method dofbot_create
 * 创建一个DOFBOT对象。
 * @param {const char*} 串口设备。
 * @return {dofbot_t*} 返回DOFBOT对象。
 */
dofbot_t* dofbot_create(const char* serial);

/**
 * @method dofbot_read_version
 * 读取 dofbot 版本号。
 * >设备端似乎并未实现。
 * @param {dofbot_t*} dofbot对象。
 * @param {int32_t*} version 版本号。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_read_version(dofbot_t* dofbot, int32_t* version);

/**
 * @method dofbot_write_servos
 * 写入关节角度(单位：度)
 * @param {dofbot_t*} dofbot对象。
 * @param {int32_t} s1 关节1角度。
 * @param {int32_t} s2 关节2角度。
 * @param {int32_t} s3 关节3角度。
 * @param {int32_t} s4 关节4角度。
 * @param {int32_t} s5 关节5角度。
 * @param {int32_t} s6 关节6角度。
 * @param {int32_t} time 角度变化时间(单位：毫秒)。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_write_servos(dofbot_t* dofbot, int32_t s1, int32_t s2, int32_t s3, int32_t s4,
                          int32_t s5, int32_t s6, int32_t time);

/**
 * @method dofbot_write_servos_array
 * 写入关节角度(单位：度)
 * @param {dofbot_t*} dofbot对象。
 * @param {int32_t[6]} values 关节角度数组。
 * @param {int32_t} time 角度变化时间(单位：毫秒)。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_write_servos_array(dofbot_t* dofbot, const int32_t values[6], int32_t time);

/**
 * @method dofbot_write_servo
 * 写入单个关节角度(单位：度)
 * @param {dofbot_t*} dofbot对象。
 * @param {uint8_t} id 关节ID。
 * @param {int32_t} angle 关节角度。
 * @param {int32_t} time 角度变化时间(单位：毫秒)。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */                     
ret_t dofbot_write_servo(dofbot_t* dofbot, uint8_t id, int32_t angle, int32_t time);

/**
 * @method dofbot_read_servo
 * 读取单个关节角度(单位：度)
 * @param {dofbot_t*} dofbot对象。
 * @param {uint8_t} id 关节ID。
 * @param {int*} value 关节角度。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_read_servo(dofbot_t* dofbot, uint8_t id, int32_t* value);

/**
 * @method dofbot_reset
 * 重置DOFBOT。
 * @param {dofbot_t*} dofbot对象。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_reset(dofbot_t* dofbot);

/**
 * @method dofbot_set_rgb
 * 设置RGB灯颜色。
 * @param {dofbot_t*} dofbot对象。
 * @param {uint8_t} r 红色分量(0-255)。
 * @param {uint8_t} g 绿色分量(0-255)。
 * @param {uint8_t} b 蓝色分量(0-255)。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_set_rgb(dofbot_t* dofbot, uint8_t r, uint8_t g, uint8_t b);

/**
 * @method dofbot_home
 * 回零所有关节。
 * @param {dofbot_t*} dofbot对象。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_home(dofbot_t* dofbot);

/**
 * @method dofbot_home_servo
 * 回零单个关节。
 * @param {dofbot_t*} dofbot对象。
 * @param {uint8_t} id 关节ID。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_home_servo(dofbot_t* dofbot, uint8_t id);

/**
 * @method dofbot_buzzer
 * 蜂鸣器鸣叫。
 * @param {dofbot_t*} dofbot对象。
 * @param {uint8_t} duration 鸣叫时间(单位：100毫秒)。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_buzzer(dofbot_t* dofbot, uint8_t duration);

/**
 * @method dofbot_set_torque_mode
 * 设置力矩模式。
 * > 力矩模式下，关节无法用手转动, 只能通过程序控制。
 * @param {dofbot_t*} dofbot对象。
 * @param {bool_t} on 是否开启力矩模式。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_set_torque_mode(dofbot_t* dofbot, bool_t on);

/**
 * @method dofbot_destroy
 * 销毁DOFBOT对象。
 * @param {dofbot_t*} dofbot对象。
 * @return {ret_t} 返回RET_OK表示成功，否则表示失败。
 */
ret_t dofbot_destroy(dofbot_t* dofbot);

END_C_DECLS

#endif /*TK_DOFBOT_H*/
